/*
 * schema.h - support for schema definition
 *
 * Copyright (c) 2003 Tiankai Tu, David R. O'Hallaron
 * All rights reserved.  May not be used, modified, or copied 
 * without permission.
 *
 * Tiankai Tu
 * Computer Science Department
 * Carnegie Mellon University
 * 5000 Forbes Avenue
 * Pittsburgh, PA 15213
 * tutk@cs.cmu.edu
 *
 */

#ifndef SCHEMA_H
#define SCHEMA_H

#include "octree_types.h"

/*
 * schema_create - create and initialize a schema
 *
 * - allocate memory for the schema application shall later call 
 *   schema_destroy to clean up
 * - parse the definition string
 * - empty defstring create a stub schema for schema_fromascii
 * - return pointer to a schema if OK, NULL on error
 *
 */
schema_t *schema_create(const char *defstring);


/*
 * schema_destroy - release memory held by a schema
 *
 *
 */
void schema_destroy(schema_t *schema); 


/*
 * schema_toascii - ASCII output of a schema to a character buffer 
 * 
 * - serialize the schema (binary format) for portable output
 * - allocate memory to hold the ASCII schema, application should later
 *   release the memory with free();
 * - return 0 if OK, -1 on error
 * - the size (strlen()) of the ascii schema is returned in *asciisizeptr
 * 
 */
char *schema_toascii(const schema_t *bin_schema, uint32_t *asciisizeptr);


/*
 * schema_fromascii - input a converted schema ASCII string into a schema
 *
 * - memory is allocated for the schema, application shall later call 
 *   schema_destroy to clean up
 * - return a  pointer to the initialized schema if OK, NULL on error
 *
 */
schema_t *schema_fromascii(const char *asc_schema);


/*
 * schema_getdefstring - reconstruct the definition string
 * 
 * - serialize the schema (binary format) for portable output
 * - allocate memory to hold the definition string, 
 * - application should later release the memory with free();
 * - return pointer to the def string if OK, NULL on error 
 * 
 */
char *schema_getdefstring(const schema_t *schema);

/*
 * schema_getfieldidx - get the index for a field with the given name
 *
 * - return 0 if no schema defined and request the whole field
 *          -13 if no schema defined and request a particular field
 *          -14 if schema defined but the field not found
 *          schema->fieldnum if schema defined and request the whole field
 *             fieldindex if schema defined and the fieldname found
 */
int schema_getfieldidx (const schema_t* schema, const char* fieldname);


#endif /* SCHEMA_H */

